home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / Tools / term-2.3.5 / README.termwrap < prev    next >
Encoding:
Text File  |  1995-07-14  |  5.5 KB  |  159 lines
  1.  
  2.             =================================
  3.             termwrap.so dynamic shared object
  4.             =================================
  5.  
  6.                       *** Only for Solaris 2.x ***
  7.  
  8.  
  9. Two line description:
  10.   It uses the cool Solaris dynamic linking facilities to allow networking
  11.   programs to use TERM without having to be recompiled or changed at all.
  12.  
  13.  
  14. HOW TO USE IT
  15. =============
  16.  
  17.   Any networking program which could be ported to use TERM by including
  18.   "termnet.h" and linking with libtermnet.a can be used "as is" with
  19.   termwrap.so. Programs which I have verified include:
  20.  
  21.      Solaris's telnet
  22.      Solaris's finger
  23.      xarchie from ftp.x.org
  24.  
  25.   When libtermnet.a matures and supports a more complete set of networking
  26.   functions, other programs like Netscape and Solaris's FTP will also
  27.   work (magically, without recompilation, of course :-)
  28.  
  29.  
  30.   Once TERM is installed and running, simply do:
  31.  
  32.      termwrap program args_to_program
  33.  
  34.      eg: termwrap telnet some_remote_hostname
  35.  
  36.   (If you installed TERM into a non-standard place you will need to set the
  37.    TERMWRAP environment variable to the location of termwrap.so first).
  38.  
  39.   "termwrap" executes "program" under TERM mode. It simply sets LD_PRELOAD
  40.   to the termwrap.so dynamic shared object, then exec's "program".
  41.  
  42.   If TERM was installed in "shared mode" (eg: make installshare), then
  43.   "termwrap" will have been installed setgid and you will get TERM shared
  44.   mode, just as if you'd recompiled "program" with libtermnet.a and changed
  45.   its modes to setgid term.
  46.  
  47.   Note that setuid and setgid programs cannot work with termwrap.so
  48.   because LD_PRELOAD is ignored for such programs. "rlogin" is an example
  49.   of such a program.
  50.  
  51.  
  52.  
  53. ERRORS
  54. ======
  55.   If, when you run a program under termwrap, you get errors such as:
  56.  
  57.      ld.so.1: program: fatal: relocation error: symbol not found: h_errno:
  58.      referenced in /usr/local/lib/termwrap.so
  59.  
  60.   then "program" is not a networking program (it is not linked with libsocket
  61.   and libnsl). Such programs cannot support TERM.
  62.  
  63.   If the program appears to start up correctly, but does not work properly,
  64.   or core dumps, or seems to be confused, or simply doesn't work at all,
  65.   then it probably uses networking functions which libtermnet doesn't
  66.   emulate. Such a program couldn't be ported by using "termnet.h" and
  67.   lintermnet.a, and therefore cannot be used with termwrap. An example of
  68.   such a program is netscape. It runs, and seems to be ok, but it can't
  69.   find any hosts over the TERM connection. Obviously it uses some functions
  70.   which libtermnet.a doesn't emulate... perhaps from libresolv? Similarly,
  71.   Solaris's FTP seems to work correctly during the login process etc, but
  72.   cannot "see" any files at the remote site... See Term.HOWTO for a list of
  73.   alternative programs you might consider using instead.
  74.  
  75.  
  76.  
  77. HOW IT WORKS
  78. ============
  79.  
  80. termwrap.so has three parts:
  81.  
  82.   termwrapin.c
  83.   ============
  84.    A set of functions with identical names to those in libsocket and libnsl.
  85.    These pass control to the libtermnet functions term_* (just as if
  86.    they had been defined using termnet.h).
  87.  
  88.   termwrapout.c
  89.   =============
  90.    A set of functions which match the above functions but have "x__"
  91.    prepended to their names. These functions do interposing using dlsym().
  92.    They call functions with same names as the ones defined in termwrapin.c,
  93.    but NOT THOSE FUNCTIONS. Instead, they call the "real" functions in 
  94.    libsocket/libnsl. (For a description of interposing, see the Solaris 
  95.    Linker & Libraries Answerbook).
  96.  
  97.   the files which make up libtermnet
  98.   ==================================
  99.    these provide the term_* emulation functions.
  100.  
  101.  
  102. In summary, here is what happens:
  103.  
  104.    NORMAL NETWORKING PROGRAM (NO TERM)
  105.    ===================================
  106.  
  107.        program calls networking function
  108.                     |
  109.                     V
  110.        libsocket or libnsl performs networking function
  111.  
  112.  
  113.    NETWORKING PROGRAM WHEN LD_PRELOAD=/usr/local/lib/termwrap.so
  114.    =============================================================
  115.  
  116.        program calls networking function
  117.                     |
  118.                     V
  119.        termwrap.so(termwrapin.c) intercepts function because of LD_PRELOAD,
  120.        and calls term_*
  121.                     |
  122.                     V
  123.        term_* does the actual talking to term by calling x__* funcs.
  124.                     |    |    |
  125.                     V    V    V
  126.        x__* (in termwrapout.c) uses dlsym(RTLD_NEXT,"*") to find the
  127.        real socket function which libtermnet thought it was calling
  128.        and calls that. Ta Da!
  129.  
  130.  
  131. As a picture it would look like this:
  132.  
  133.                         networking program
  134.                          V             ^
  135.                          V             ^
  136.         +----------------V-------------^-----------+
  137.         | termwrapin.c   V             ^           |
  138.         +----------------V-------------^-----------+
  139.         |                                          |
  140.         |                  libtermnet              |
  141.         |                                          |
  142.         +------------------V-^-V-^-V-^-------------+
  143.         | termwrapout.c    V ^ V ^ V ^             |
  144.         +------------------V-^-V-^-V-^-------------+
  145.                            V ^ V ^ V ^
  146.                            V ^ V ^ V ^
  147.                         libsocket and libnsl
  148.  
  149.                Time ----> ----> ----> ----> ---->
  150.  
  151.  
  152. If after all that explaining I've only managed to confuse you, check out
  153. the section on "Interposing" in the "Solaris Linker & Libraries Answerbook".
  154.  
  155. Feel free to email me if you have any questions...
  156.  
  157.  
  158. JASON PATTERSON (jasonp@fit.qut.edu.au)
  159.